iT邦幫忙

第 12 屆 iThome 鐵人賽

DAY 20
1

Laravel優勢:有許多強大套件,apiDoc也是其中之一。

相較於Postman,有以下優缺點:

優勢

  • 版本控制
  • 一套IDE就能同時寫code跟文件

缺勢

  • 上手難度較高(指令較多、也須注意系統版本問題、綁定 domain url路徑)
  • 美感
  • 無法局部開放API文件內容,或許可透過git branch分支處理。

基本建置

step 1:從composer安裝套件

composer require --dev mpociot/laravel-apidoc-generator

step 2:再用php artisan vendor

php artisan vendor:publish --provider="Mpociot\ApiDoc\ApiDocGeneratorServiceProvider" --tag=apidoc-config

在 config 資料夾內會多一個 apidoc.php 。

step 3:建立apidoc指令

php artisan apidoc:generate

  • 更新apiDoc內容也是這指令 或 php artisan apidoc:rebuild
  • 如果快取未清除,先下php artisan config:clear 試試。

step 4:進入網址

預設網址通常是 http://127.0.0.1:8000/docs/index.html

會看到類似的網頁
https://ithelp.ithome.com.tw/upload/images/20201005/201252630mpzi518Rc.png

分別提供bash跟javascript語法的request指令->這點輸Postman。

範例指令

基本上只要是放在router的路徑都會顯示。

以下範例為 Task CRUD的 apiDoc指令介紹。

API分組指令

  • @group 放在class之前,可將該class內的方法統整為一個group
  • 可作說明,但未支援額外的markdown
    https://ithelp.ithome.com.tw/upload/images/20201005/20125263vcHkqXHt6w.png

單一API說明

以 store action為例
https://ithelp.ithome.com.tw/upload/images/20201005/20125263NFYmax1CDU.png

  • 第一行 h1規格的標題
  • 第二行 一般文字規格的說明
  • @bodyParam 用空格區分 Parameter 名稱、 Type 資料型態、 Status 是否必需或選填、Description說明
  • 如果在 @bodyParam 加上 Example後會出現在範例request指令中
  • @response 可以填寫成功或失敗案例。不填寫http狀態碼預設為200

更新

  • 一定要重下指令才會同步更新在apiDoc的網頁上
  • php artisan apidoc:generatephp artisan apidoc:rebuild

參考資料
https://github.com/mpociot/laravel-apidoc-generator
https://beyondco.de/docs/laravel-apidoc-generator/getting-started/installation
https://www.youtube.com/watch?v=QQS5oEOguRU
https://packagist.org/packages/mpociot/laravel-apidoc-generator
https://ithelp.ithome.com.tw/articles/10226634


上一篇
Postman:API客戶端測試與線上文件
下一篇
File Storage:圖片上傳功能
系列文
30天開發與部署 Laravel 專案30
圖片
  直播研討會
圖片
{{ item.channelVendor }} {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言